Download
FAQ
History
HomeHomeNext API
Search
Feedback
Divider

A Simple J2EE Application that Uses the JMS API

This section explains how to write, compile, package, deploy, and run a simple J2EE application that uses the JMS API. The application in this section uses the following components:

The section covers the following topics:

You will find the source files for this section in the directory <INSTALL>/j2eetutorial14/examples/jms/clientmdb/. Path names in this section are relative to this directory.

Writing the Application Components

This first and simplest application contains the following components:

Figure 21-1 illustrates the structure of this application.

A Simple J2EE Application: Client to Message-Driven Bean

Figure 21-1 A Simple J2EE Application: Client to Message-Driven Bean

The application client sends messages to the queue. The JMS provider--in this case, the J2EE server--delivers the messages to the message-driven bean instances, which then process the messages.

Writing the components of this application involves

Coding the Application Client: SimpleClient.java

The application client class, src/SimpleClient.java, is almost identical to <INSTALL>/j2eetutorial14/examples/jms/simple/SimpleProducer.java in Writing the Client Programs. The only significant differences are as follows.

Coding the Message-Driven Bean: MessageBean.java

The message-driven bean class, src/MessageBean.java, implements the methods setMessageDrivenContext, ejbCreate, onMessage, and ejbRemove. The onMessage method, almost identical to that of <INSTALL>/j2eetutorial14/examples/jms/simple/TextListener.java in Writing the Client Programs, casts the incoming message to a TextMessage and displays the text. The only significant difference is that it calls the MessageDrivenContext.setRollbackOnly method in case of an exception. This method rolls back the transaction so that the message will be redelivered.

Creating and Packaging the Application

This example uses a connection factory named jms/QueueConnectionFactory and a queue named jms/Queue, both of which you created in Creating the JMS Administered Objects for the Simple Examples.

Creating and packaging this application involve several steps:

Compiling the Source Files and Starting the J2EE Application Server

  1. Use the build target to compile the source files:
  2. asant build

  3. Start the J2EE Application Server, if it is not already running.

Starting the J2EE Deploytool and Creating the Application

  1. Start the deploytool:
  2. On Windows systems, choose StartRight ArrowProgramsRight ArrowSun MicrosystemsRight ArrowJ2EE 1.4 SDKRight ArrowDeploytool.

    On UNIX systems, use the deploytool command.

  3. Choose FileRight ArrowNewRight ArrowApplication EAR.
  4. Click Browse next to the Application File Name field and use the file chooser to locate the directory clientmdb.
  5. In the File Name field, type ClientMDBApp.
  6. Click New Application.
  7. Click OK.

Packaging the Application Client

To package the application client, perform the following steps:

  1. Choose FileRight ArrowNewRight ArrowApplication Client JAR to start the Application Client Wizard.
  2. In the JAR File Contents screen:
    1. Verify that Create New AppClient Module in Application is selected and that the application is ClientMDBApp.
    2. In the AppClient Display Name field, type SimpleClient.
    3. Click the Edit button next to the Contents text area.
    4. In the dialog box, locate the build/client/ directory. Select SimpleClient.class from the Available Files tree area and click Add, then OK.
  3. In the General screen, select client.SimpleClient in the Main Class combo box.
  4. In the Message Destination References screen, click Add. In the dialog box:
    1. Type jms/QueueName in the Coded Name field.
    2. Choose javax.jms.Queue from the Destination Type menu.
    3. Choose Produces from the Usage menu.
    4. Type PhysicalQueue in the Destination Name field.
  5. In the Resource References screen:
    1. Click Add.
    2. Type jms/MyConnectionFactory in the Coded Name field.
    3. Choose javax.jms.ConnectionFactory from the Type menu.
    4. Type jms/QueueConnectionFactory in the JNDI name field and j2ee in both the User Name and Password fields.
  6. Click Finish.
  7. Click the Message Destinations tab. In the inspector pane:
    1. Click Add.
    2. Type PhysicalQueue in the Destination Name field. When you press Enter, this name appears in the Display Name field, and SimpleClient appears in the Producers area.
    3. Type jms/Queue in the JNDI Name field.

Packaging the Message-Driven Bean

To package the message-driven bean, perform the following steps:

  1. Choose FileRight ArrowNewRight ArrowEnterprise JavaBean JAR to start the Enterprise Bean Wizard, then click Next.
  2. In the EJB JAR screen:
    1. Select Create New JAR Module in Application and verify that the application is ClientMDBApp.
    2. In the JAR Display Name field, type MDBJAR.
    3. Click the Edit button next to the Contents text area.
    4. In the dialog box, locate the build/mdb/ directory. Select MessageBean.class from the Available Files tree area and click Add, then OK.
  3. In the General screen:
    1. Choose the Message-Driven radio button.
    2. From the Enterprise Bean Class menu, choose mdb.MessageBean.
    3. In the Enterprise Bean Display Name field, accept the default value, MessageBean.
  4. In the Configuration Options screen, check the Transaction Management box.
  5. In the Message-Driven Bean Settings screen:
    1. For the Message Listener Interface, accept the default, javax.jms.MessageListener. (You accept this default in every example.)
    2. Click Add in the Activation Configuration Properties area. This is where you specify the required activation configuration properties for the bean.
    3. Type destination in the Property Name field and PhysicalQueue in the Value field.
    4. Click Add again.
    5. Type destinationType in the Property Name field and javax.jms.Queue in the Value field.
    6. Choose javax.jms.Queue from the Destination Type menu.
    7. Type PhysicalQueue in the Destination Name field.
    8. Click Deployment Settings. In the dialog box, type jmsra in the Resource Adapter field and click OK.
  6. In the Transaction Management screen, choose Container-Managed.
  7. Click Finish.
  8. Click the Message Destinations tab. In the inspector pane:
    1. Click Add.
    2. Type PhysicalQueue in the Destination Name field. When you press Enter, this name appears in the Display Name field, SimpleClient appears in the Producers area, and MessageBean appears in the Consumers area.
    3. Type jms/Queue in the JNDI Name field.

Updating the JNDI Names

In the J2EE Application Server, the JNDI name for a message-driven bean is the destination it receives messages from, not the bean name.

  1. Select the application and click the JNDI Names tab.
  2. Type jms/Queue in the JNDI Name field for the MessageBean component.

Verify that the JNDI names for the application components are correct. They should appear as shown in Table 21-1 and Table 21-2.

Table 21-1 Application Pane for ClientMDBApp
Component Type
Component
JNDI Name
EJB
MessageBean
jms/Queue

Table 21-2 References Pane for ClientMDBApp
Ref. Type
Referenced By
Reference Name
JNDI Name
Resource
SimpleClient
jms/MyConnectionFactory
jms/QueueConnectionFactory

Deploying the Application

  1. Choose FileRight ArrowSave to save the application.
  2. Choose ToolsRight ArrowDeploy.
  3. In the dialog box, type your administrative user name and password (if they are not already filled in) and click OK.
  4. In the Distribute Module dialog box, click Close when the process completes.

Saving the Client JAR and Running the Application

  1. In the deploytool, select the server node.
  2. Select ClientMDBApp from the list of deployed objects, then click Client Jar.
  3. Choose Browse to navigate to the directory from which you will run the client. Specify the clientmdb directory, click Select, then click OK. Click OK in the information dialog. You will find a file named ClientMDBAppClient.jar in the specified directory.
  4. To run the client, use the following command:
  5. appclient -client ClientMDBAppClient.jar

The program output in the terminal window looks something like this:

Sending message: This is message 1
Sending message: This is message 2
Sending message: This is message 3 

The output from the message-driven bean appears in the server log file, <J2EE_HOME>/domains/domain1/server/logs/server.log:

In MessageBean.MessageBean()
In MessageBean.setMessageDrivenContext()
In MessageBean.ejbCreate()
MESSAGE BEAN: Message received: This is message 1
MESSAGE BEAN: Message received: This is message 2
MESSAGE BEAN: Message received: This is message 3 

Undeploying and Removing the Application

To undeploy and remove the application, perform the following steps:

  1. Select the deployed application in the server pane and click Undeploy.
  2. Select the application in the left-hand pane and choose FileRight ArrowClose.
  3. Remove the build directory created by the build target:
  4. asant clean

  5. If you wish, stop the server:
  6. asadmin stop-domain

If you wish, you can manually delete the EAR and client JAR files.

Divider
Download
FAQ
History
HomeHomeNext API
Search
Feedback
Divider

All of the material in The J2EE 1.4 Tutorial is copyright-protected and may not be published in other works without express written permission from Sun Microsystems.